Write documentation Write documentation
authorJonathan Blandford <jrb@redhat.com>
Sat, 8 Sep 2001 18:23:47 +0000 (18:23 +0000)
committerJonathan Blandford <jrb@src.gnome.org>
Sat, 8 Sep 2001 18:23:47 +0000 (18:23 +0000)
Sat Sep  8 14:19:49 2001  Jonathan Blandford  <jrb@redhat.com>

* gtk/gtkliststore.c: Write documentation
* gtk/gtktreestore.c: Write documentation

Quick Documentation cleanup pass.

16 files changed:
ChangeLog
ChangeLog.pre-2-0
ChangeLog.pre-2-10
ChangeLog.pre-2-2
ChangeLog.pre-2-4
ChangeLog.pre-2-6
ChangeLog.pre-2-8
docs/reference/gtk/tmpl/gtk-unused.sgml
docs/reference/gtk/tmpl/gtkcontainer.sgml
docs/reference/gtk/tmpl/gtkliststore.sgml
docs/reference/gtk/tmpl/gtktreemodel.sgml
docs/reference/gtk/tree_widget.sgml
gtk/gtkliststore.c
gtk/gtkliststore.h
gtk/gtktreeselection.c
gtk/gtktreestore.c

index fff88df6c12822001f7ed91022da09435a9a58fe..bb7d80a9f9ea7150494793b57291e67a5ad90d48 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+Sat Sep  8 14:19:49 2001  Jonathan Blandford  <jrb@redhat.com>
+
+       * gtk/gtkliststore.c: Write documentation
+       * gtk/gtktreestore.c: Write documentation
+
 Sat Sep  8 13:53:09 2001  Owen Taylor  <otaylor@redhat.com>
 
        * gtk/gtkrc.[ch] gtk/gtkstyle.[ch]: Replace uses of GBSearchArray
index fff88df6c12822001f7ed91022da09435a9a58fe..bb7d80a9f9ea7150494793b57291e67a5ad90d48 100644 (file)
@@ -1,3 +1,8 @@
+Sat Sep  8 14:19:49 2001  Jonathan Blandford  <jrb@redhat.com>
+
+       * gtk/gtkliststore.c: Write documentation
+       * gtk/gtktreestore.c: Write documentation
+
 Sat Sep  8 13:53:09 2001  Owen Taylor  <otaylor@redhat.com>
 
        * gtk/gtkrc.[ch] gtk/gtkstyle.[ch]: Replace uses of GBSearchArray
index fff88df6c12822001f7ed91022da09435a9a58fe..bb7d80a9f9ea7150494793b57291e67a5ad90d48 100644 (file)
@@ -1,3 +1,8 @@
+Sat Sep  8 14:19:49 2001  Jonathan Blandford  <jrb@redhat.com>
+
+       * gtk/gtkliststore.c: Write documentation
+       * gtk/gtktreestore.c: Write documentation
+
 Sat Sep  8 13:53:09 2001  Owen Taylor  <otaylor@redhat.com>
 
        * gtk/gtkrc.[ch] gtk/gtkstyle.[ch]: Replace uses of GBSearchArray
index fff88df6c12822001f7ed91022da09435a9a58fe..bb7d80a9f9ea7150494793b57291e67a5ad90d48 100644 (file)
@@ -1,3 +1,8 @@
+Sat Sep  8 14:19:49 2001  Jonathan Blandford  <jrb@redhat.com>
+
+       * gtk/gtkliststore.c: Write documentation
+       * gtk/gtktreestore.c: Write documentation
+
 Sat Sep  8 13:53:09 2001  Owen Taylor  <otaylor@redhat.com>
 
        * gtk/gtkrc.[ch] gtk/gtkstyle.[ch]: Replace uses of GBSearchArray
index fff88df6c12822001f7ed91022da09435a9a58fe..bb7d80a9f9ea7150494793b57291e67a5ad90d48 100644 (file)
@@ -1,3 +1,8 @@
+Sat Sep  8 14:19:49 2001  Jonathan Blandford  <jrb@redhat.com>
+
+       * gtk/gtkliststore.c: Write documentation
+       * gtk/gtktreestore.c: Write documentation
+
 Sat Sep  8 13:53:09 2001  Owen Taylor  <otaylor@redhat.com>
 
        * gtk/gtkrc.[ch] gtk/gtkstyle.[ch]: Replace uses of GBSearchArray
index fff88df6c12822001f7ed91022da09435a9a58fe..bb7d80a9f9ea7150494793b57291e67a5ad90d48 100644 (file)
@@ -1,3 +1,8 @@
+Sat Sep  8 14:19:49 2001  Jonathan Blandford  <jrb@redhat.com>
+
+       * gtk/gtkliststore.c: Write documentation
+       * gtk/gtktreestore.c: Write documentation
+
 Sat Sep  8 13:53:09 2001  Owen Taylor  <otaylor@redhat.com>
 
        * gtk/gtkrc.[ch] gtk/gtkstyle.[ch]: Replace uses of GBSearchArray
index fff88df6c12822001f7ed91022da09435a9a58fe..bb7d80a9f9ea7150494793b57291e67a5ad90d48 100644 (file)
@@ -1,3 +1,8 @@
+Sat Sep  8 14:19:49 2001  Jonathan Blandford  <jrb@redhat.com>
+
+       * gtk/gtkliststore.c: Write documentation
+       * gtk/gtktreestore.c: Write documentation
+
 Sat Sep  8 13:53:09 2001  Owen Taylor  <otaylor@redhat.com>
 
        * gtk/gtkrc.[ch] gtk/gtkstyle.[ch]: Replace uses of GBSearchArray
index 5a4532ffa3a7f1fd07e6d40c91cf2b29f1bb619b..658a0dc6a7fc91b44f384e4f3b4ef79e4a1e39b5 100644 (file)
@@ -225,6 +225,12 @@ has the focus.
 
 @clist: The #GtkCList widget to check.
 
+<!-- ##### MACRO GTK_HAVE_CONTAINER_FOCUS_ADJUSTMENTS ##### -->
+<para>
+
+</para>
+
+
 <!-- ##### MACRO GTK_ICON_SIZE_BUTTON ##### -->
 <para>
 
index 4fa9b0e086fb1220754875455d76510d9c43b0f9..8c7596d839e68ebed5e2d8e8c59afc79110f2c31 100644 (file)
@@ -38,13 +38,6 @@ GtkContainer
 @pspec: 
 
 
-<!-- ##### MACRO GTK_HAVE_CONTAINER_FOCUS_ADJUSTMENTS ##### -->
-<para>
-
-</para>
-
-
-
 <!-- ##### MACRO gtk_container_border_width ##### -->
 <para>
 
index a83c4cef946982c62ac04ae7b4a3b29b357a187c..35ae04ce37f40cee4ea57c5add9c4b0c105c762c 100644 (file)
@@ -36,8 +36,10 @@ GtkListStore
 
 </para>
 
-@store: 
+@list_store: 
 @iter: 
+<!-- # Unused Parameters # -->
+@store: 
 
 
 <!-- ##### FUNCTION gtk_list_store_insert ##### -->
@@ -45,9 +47,11 @@ GtkListStore
 
 </para>
 
-@store: 
+@list_store: 
 @iter: 
 @position: 
+<!-- # Unused Parameters # -->
+@store: 
 
 
 <!-- ##### FUNCTION gtk_list_store_insert_before ##### -->
@@ -55,9 +59,11 @@ GtkListStore
 
 </para>
 
-@store: 
+@list_store: 
 @iter: 
 @sibling: 
+<!-- # Unused Parameters # -->
+@store: 
 
 
 <!-- ##### FUNCTION gtk_list_store_insert_after ##### -->
@@ -65,9 +71,11 @@ GtkListStore
 
 </para>
 
-@store: 
+@list_store: 
 @iter: 
 @sibling: 
+<!-- # Unused Parameters # -->
+@store: 
 
 
 <!-- ##### FUNCTION gtk_list_store_prepend ##### -->
@@ -75,8 +83,10 @@ GtkListStore
 
 </para>
 
-@store: 
+@list_store: 
 @iter: 
+<!-- # Unused Parameters # -->
+@store: 
 
 
 <!-- ##### FUNCTION gtk_list_store_append ##### -->
@@ -84,7 +94,9 @@ GtkListStore
 
 </para>
 
-@store: 
+@list_store: 
 @iter: 
+<!-- # Unused Parameters # -->
+@store: 
 
 
index ecdc8bca810b3d683e229ce5b602d3c276a7694a..7aaa1d9aba1aec1826ffbd186e1b3a7646962176 100644 (file)
@@ -1,8 +1,8 @@
 <!-- ##### SECTION Title ##### -->
-gtktreemodel
+GtkTreeModel
 
 <!-- ##### SECTION Short_Description ##### -->
-
+The tree interface used by #GtkTreeView
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
@@ -11,7 +11,7 @@ gtktreemodel
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
-
+#GtkTreeView, #GtkTreeStore, #GtkListStore
 </para>
 
 <!-- ##### MACRO GTK_TREE_MODEL_GET_IFACE ##### -->
index 7efe6491f5a5c284893ef5ae0d7b1461d07af3e2..c47fc1f646fb6096460811be313a3d40ab7e3e87 100644 (file)
@@ -7,7 +7,9 @@
 
   <refnamediv>
     <refname>Tree and List Widget Overview</refname>
-    <refpurpose>Overview of <link linkend="GtkTreeModel">GtkTreeModel</link>, <link linkend="GtkTreeView">GtkTreeView</link>, and friends</refpurpose>
+    <refpurpose>Overview of <link
+    linkend="GtkTreeModel">GtkTreeModel</link>, <link
+    linkend="GtkTreeView">GtkTreeView</link>, and other assocoiated widgets</refpurpose>
   </refnamediv>
 
   <refsect1>
       To create a tree or list in GTK+, you need to use the <link
       linkend="GtkTreeModel">GtkTreeModel</link> interface, in
       conjunction with the <link
-      linkend="GtkTreeView">GtkTreeView</link>.
+      linkend="GtkTreeView">GtkTreeView</link> widget.
     </para>
     <para>
-      <emphasis>Write real docs here</emphasis>
+      This widget is designed around a
+      <firstterm>Model/View/Controller</firstterm> design and consists
+      of four major parts:
+      <simplelist>
+       <member>the tree view widget (GtkTreeView)</member>
+       <member>the view column (GtkTreeViewColumn)</member>
+       <member>the cell renderers (GtkCellRenderer etc.)</member>
+       <member>and the model interface (GtkTreeModel)</member>
+      </simplelist>
+      The <emphasis>View</empahsis> is composed of the first three,
+       while the last is the <empahsis>Model</empahsis>.  One of the
+       prime benefits of the MVC design is that multiple views can be
+       created of a single model.  For example, a model mapping the file
+       system could be created for a file manager.  Many views could be
+       created to display various parts of the file system, but only one
+       copy need be kept in memory.
     </para>
   </refsect1>
-  
-
   <refsect1>
     <title>Simple Example</title>
     <para>
@@ -31,7 +46,9 @@
       linkend="GtkTreeView">GtkTreeView</link> widget in context of the
       other widgets.  It simply creates a simple model and view, and
       puts them together.  Note that the model is never populated with
-      data &mdash; that is left as an exercise for the reader.
+      data &mdash; that is left as an exercise for the reader.  More
+      information can be found on this in the <link
+      linkend="GtkTreeStore">GtkTreeModel</link> section.
       <programlisting><![CDATA[
 {
   GtkTreeStore *model;
@@ -42,6 +59,7 @@
   /* Create a model.  We are using the store model for now, though we
    * could use any other GtkTreeModel */
   model = gtk_tree_store_new_with_values (1, G_TYPE_STRING);
+  populate_tree_model (model);
 
   /* Create a view */
   view = gtk_tree_view_new_with_model (GTK_TREE_MODEL (model));
    * reference */
   g_object_unref (G_OBJECT (model));
 
-  /* Create a cell render and set an attribute */
+  /* Create a cell render and arbitrarily make it red for demonstartion
+   *purposes */
   cell_renderer = gtk_cell_renderer_text_new ();
-  g_object_set (G_OBJECT (cell_renderer),
-               "foreground", "red",
-               NULL);
+  g_object_set (G_OBJECT (cell_renderer), "foreground", "red", NULL);
 
   /* Create a column, associating the "text" attribute of the
    * cell_renderer to the first column of the model */
@@ -70,5 +87,4 @@
       </programlisting>
     </para>
   </refsect1>
-
 </refentry>
index 50e17a7261214b12394297daf400addb46617189..3223382f803b110fc536d591b760f5a497b06081 100644 (file)
@@ -572,15 +572,10 @@ gtk_list_store_iter_parent (GtkTreeModel *tree_model,
   return FALSE;
 }
 
-/* Public accessors */
-/* This is a somewhat inelegant function that does a lot of list
- * manipulations on it's own.
- */
-
 /**
  * gtk_list_store_set_value:
- * @store: a #GtkListStore
- * @iter: iterator for the row you're modifying
+ * @list_store: A #GtkListStore
+ * @iter: A valid #GtkTreeIter for the row being modified
  * @column: column number to modify
  * @value: new value for the cell
  *
@@ -688,11 +683,11 @@ gtk_list_store_set_value (GtkListStore *list_store,
 
 /**
  * gtk_list_store_set_valist:
- * @list_store: a #GtkListStore
- * @iter: row to set data for
+ * @list_store: A #GtkListStore
+ * @iter: A valid #GtkTreeIter for the row being modified
  * @var_args: va_list of column/value pairs
  *
- * See gtk_list_store_set(); this version takes a va_list for
+ * See @gtk_list_store_set; this version takes a va_list for
  * use by language bindings.
  *
  **/
@@ -837,11 +832,10 @@ gtk_list_store_remove_silently (GtkListStore *list_store,
 
 /**
  * gtk_list_store_remove:
- * @store: a #GtkListStore
- * @iter: a row in @list_store
+ * @list_store: A #GtkListStore
+ * @iter: A valid #GtkTreeIter
  *
- * Removes the given row from the list store, emitting the
- * "deleted" signal on #GtkTreeModel.
+ * Removes the given row from the list store.  After being removed, @iter is set to be the next valid row, or invalidated if it pointed to the last row inn @list_store
  *
  **/
 void
@@ -849,10 +843,12 @@ gtk_list_store_remove (GtkListStore *list_store,
                       GtkTreeIter  *iter)
 {
   GtkTreePath *path;
+  GSList *next;
 
   g_return_if_fail (GTK_IS_LIST_STORE (list_store));
   g_return_if_fail (VALID_ITER (iter, list_store));
 
+  next = G_SLIST (iter->user_data)->next;
   path = gtk_list_store_get_path (GTK_TREE_MODEL (list_store), iter);
 
   validate_list_store (list_store);
@@ -864,6 +860,16 @@ gtk_list_store_remove (GtkListStore *list_store,
   list_store->stamp ++;
   gtk_tree_model_deleted (GTK_TREE_MODEL (list_store), path);
   gtk_tree_path_free (path);
+
+  if (next)
+    {
+      iter->stamp = list_store->stamp;
+      iter->user_data = next;
+    }
+  else
+    {
+      iter->stamp = 0;
+    }
 }
 
 static void
@@ -887,13 +893,15 @@ insert_after (GtkListStore *list_store,
 
 /**
  * gtk_list_store_insert:
- * @store: a #GtkListStore
- * @iter: iterator to initialize with the new row
+ * @list_store: A #GtkListStore
+ * @iter: An unset #GtkTreeIter to set to the new row
  * @position: position to insert the new row
  *
- * Creates a new row at @position, initializing @iter to point to the
- * new row, and emitting the "inserted" signal from the #GtkTreeModel
- * interface.
+ * Creates a new row at @position.  @iter will be changed to point to this new
+ * row.  If @position is larger than the number of rows on the list, then the
+ * new row will be appended to the list.  The row will be empty before this
+ * function is called.  To fill in values, you need to call @gtk_list_store_set
+ * or @gtk_list_store_set_value.
  *
  **/
 void
@@ -941,13 +949,14 @@ gtk_list_store_insert (GtkListStore *list_store,
 
 /**
  * gtk_list_store_insert_before:
- * @store: a #GtkListStore
- * @iter: iterator to initialize with the new row
- * @sibling: an existing row
+ * @list_store: A #GtkListStore
+ * @iter: An unset #GtkTreeIter to set to the new row
+ * @sibling: A valid #GtkTreeIter, or %NULL
  *
- * Inserts a new row before @sibling, initializing @iter to point to
- * the new row, and emitting the "inserted" signal from the
- * #GtkTreeModel interface.
+ * Inserts a new row before @sibling.  If @sibling is %NULL, then the row will be
+ * appended to the beginning of the list.  @iter will be changed to point to
+ * this new row.  The row will be empty before this function is called.  To fill
+ * in values, you need to call @gtk_list_store_set or @gtk_list_store_set_value.
  *
  **/
 void
@@ -1028,13 +1037,14 @@ gtk_list_store_insert_before (GtkListStore *list_store,
 
 /**
  * gtk_list_store_insert_after:
- * @store: a #GtkListStore
- * @iter: iterator to initialize with the new row
- * @sibling: an existing row
+ * @list_store: A #GtkListStore
+ * @iter: An unset #GtkTreeIter to set to the new row
+ * @sibling: A valid #GtkTreeIter, or %NULL
  *
- * Inserts a new row after @sibling, initializing @iter to point to
- * the new row, and emitting the "inserted" signal from the
- * #GtkTreeModel interface.
+ * Inserts a new row after @sibling.  If @sibling is %NULL, then the row will be
+ * prepended to the beginning of the list.  @iter will be changed to point to
+ * this new row.  The row will be empty after this function is called.  To fill
+ * in values, you need to call @gtk_list_store_set or @gtk_list_store_set_value.
  *
  **/
 void
@@ -1080,12 +1090,12 @@ gtk_list_store_insert_after (GtkListStore *list_store,
 
 /**
  * gtk_list_store_prepend:
- * @store: a #GtkListStore
- * @iter: iterator to initialize with new row
+ * @list_store: A #GtkListStore
+ * @iter: An unset #GtkTreeIter to set to the prepend row
  *
- * Prepends a row to @store, initializing @iter to point to the
- * new row, and emitting the "inserted" signal on the #GtkTreeModel
- * interface for the @store.
+ * Prepend a new row to @list_store.  @iter will be changed to point to this new
+ * row.  The row will be empty after this function is called.  To fill in
+ * values, you need to call @gtk_list_store_set or @gtk_list_store_set_value.
  *
  **/
 void
@@ -1118,12 +1128,12 @@ gtk_list_store_prepend (GtkListStore *list_store,
 
 /**
  * gtk_list_store_append:
- * @store: a #GtkListStore
- * @iter: iterator to initialize with the new row
+ * @list_store: A #GtkListStore
+ * @iter: An unset #GtkTreeIter to set to the appended row
  *
- * Appends a row to @store, initializing @iter to point to the
- * new row, and emitting the "inserted" signal on the #GtkTreeModel
- * interface for the @store.
+ * Appends a new row to @list_store.  @iter will be changed to point to this new
+ * row.  The row will be empty after this function is called.  To fill in
+ * values, you need to call @gtk_list_store_set or @gtk_list_store_set_value.
  *
  **/
 void
index 6549087c8972ad823bf6d7f5e2540e85cfebafb6..10364ac2b15481c674e0efea28a86f3b36eb43e0 100644 (file)
@@ -67,7 +67,7 @@ GtkListStore *gtk_list_store_new             (gint          n_columns,
                                              ...);
 GtkListStore *gtk_list_store_newv            (gint          n_columns,
                                              GType        *types);
-void          gtk_list_store_set_value       (GtkListStore *store,
+void          gtk_list_store_set_value       (GtkListStore *list_store,
                                              GtkTreeIter  *iter,
                                              gint          column,
                                              GValue       *value);
@@ -77,22 +77,22 @@ void          gtk_list_store_set             (GtkListStore *list_store,
 void          gtk_list_store_set_valist      (GtkListStore *list_store,
                                              GtkTreeIter  *iter,
                                              va_list       var_args);
-void          gtk_list_store_remove          (GtkListStore *store,
+void          gtk_list_store_remove          (GtkListStore *list_store,
                                              GtkTreeIter  *iter);
-void          gtk_list_store_insert          (GtkListStore *store,
+void          gtk_list_store_insert          (GtkListStore *list_store,
                                              GtkTreeIter  *iter,
                                              gint          position);
-void          gtk_list_store_insert_before   (GtkListStore *store,
+void          gtk_list_store_insert_before   (GtkListStore *list_store,
                                              GtkTreeIter  *iter,
                                              GtkTreeIter  *sibling);
-void          gtk_list_store_insert_after    (GtkListStore *store,
+void          gtk_list_store_insert_after    (GtkListStore *list_store,
                                              GtkTreeIter  *iter,
                                              GtkTreeIter  *sibling);
-void          gtk_list_store_prepend         (GtkListStore *store,
+void          gtk_list_store_prepend         (GtkListStore *list_store,
                                              GtkTreeIter  *iter);
-void          gtk_list_store_append          (GtkListStore *store,
+void          gtk_list_store_append          (GtkListStore *list_store,
                                              GtkTreeIter  *iter);
-void          gtk_list_store_clear           (GtkListStore *store);
+void          gtk_list_store_clear           (GtkListStore *list_store);
 
 
 #ifdef __cplusplus
index b09d00781389f07b188db26cd6e03d5b27d1caa5..3105c8646998bc1ae7c47876de6a7c773f8efb8a 100644 (file)
@@ -276,7 +276,15 @@ gtk_tree_selection_get_user_data (GtkTreeSelection *selection)
   return selection->user_data;
 }
 
-GtkTreeView*
+/**
+ * gtk_tree_selection_get_tree_view:
+ * @selection: A #GtkTreeSelection
+ * 
+ * Returns the tree view associated with @selection.
+ * 
+ * Return value: A #GtkTreeView
+ **/
+GtkTreeView *
 gtk_tree_selection_get_tree_view (GtkTreeSelection *selection)
 {
   g_return_val_if_fail (GTK_IS_TREE_SELECTION (selection), NULL);
index 6d17ba32155393bd4b51914a1defe81e30786d97..d6a1c21336f3d828e54f2cb4840e208e199a5bdd 100644 (file)
@@ -244,7 +244,11 @@ static void
 gtk_tree_store_init (GtkTreeStore *tree_store)
 {
   tree_store->root = g_node_new (NULL);
-  tree_store->stamp = g_random_int ();
+  do
+    {
+      tree_store->stamp = g_random_int ();
+    }
+  while (tree_store->stamp != 0);
   tree_store->sort_list = NULL;
   tree_store->sort_column_id = -2;
 }
@@ -684,10 +688,18 @@ gtk_tree_store_iter_parent (GtkTreeModel *tree_model,
     return FALSE;
 }
 
-/*
- * This is a somewhat inelegant function that does a lot of list
- * manipulations on it's own.
- */
+/**
+ * gtk_tree_store_set_value:
+ * @tree_store: a #GtkTreeStore
+ * @iter: A valid #GtkTreeIter for the row being modified
+ * @column: column number to modify
+ * @value: new value for the cell
+ *
+ * Sets the data in the cell specified by @iter and @column.
+ * The type of @value must be convertible to the type of the
+ * column.
+ *
+ **/
 void
 gtk_tree_store_set_value (GtkTreeStore *tree_store,
                          GtkTreeIter  *iter,
@@ -786,11 +798,11 @@ gtk_tree_store_set_value (GtkTreeStore *tree_store,
 
 /**
  * gtk_tree_store_set_valist:
- * @tree_store: a #GtkTreeStore
- * @iter: row to set data for
+ * @tree_store: A #GtkTreeStore
+ * @iter: A valid #GtkTreeIter for the row being modified
  * @var_args: va_list of column/value pairs
  *
- * See gtk_tree_store_set(); this version takes a va_list for
+ * See @gtk_tree_store_set; this version takes a va_list for
  * use by language bindings.
  *
  **/
@@ -844,8 +856,8 @@ gtk_tree_store_set_valist (GtkTreeStore *tree_store,
 
 /**
  * gtk_tree_store_set:
- * @tree_store: a #GtkTreeStore
- * @iter: row iterator
+ * @tree_store: A #GtkTreeStore
+ * @iter: A valid #GtkTreeIter for the row being modified
  * @Varargs: pairs of column number and value, terminated with -1
  *
  * Sets the value of one or more cells in the row referenced by @iter.
@@ -870,60 +882,85 @@ gtk_tree_store_set (GtkTreeStore *tree_store,
   va_end (var_args);
 }
 
+/**
+ * gtk_tree_store_remove:
+ * @tree_store: A #GtkTreeStore
+ * @iter: A valid #GtkTreeIter
+ * 
+ * Removes @iter from @tree_store.  After being removed, @iter is set to the
+ * next valid row at that level, or invalidated if it previeously pointed to the last one.
+ **/
 void
-gtk_tree_store_remove (GtkTreeStore *model,
+gtk_tree_store_remove (GtkTreeStore *tree_store,
                       GtkTreeIter  *iter)
 {
   GtkTreePath *path;
   GtkTreeIter new_iter = {0,};
   GNode *parent;
+  GNode *next_node;
 
-  g_return_if_fail (GTK_IS_TREE_STORE (model));
-  g_return_if_fail (VALID_ITER (iter, model));
+  g_return_if_fail (GTK_IS_TREE_STORE (tree_store));
+  g_return_if_fail (VALID_ITER (iter, tree_store));
 
   parent = G_NODE (iter->user_data)->parent;
 
   g_assert (parent != NULL);
+  next_node = G_NODE (iter->user_data);
 
   if (G_NODE (iter->user_data)->data)
     _gtk_tree_data_list_free ((GtkTreeDataList *) G_NODE (iter->user_data)->data,
-                             model->column_headers);
+                             tree_store->column_headers);
 
-  path = gtk_tree_store_get_path (GTK_TREE_MODEL (model), iter);
+  path = gtk_tree_store_get_path (GTK_TREE_MODEL (tree_store), iter);
   g_node_destroy (G_NODE (iter->user_data));
 
-  model->stamp++;
-  gtk_tree_model_deleted (GTK_TREE_MODEL (model), path);
+  tree_store->stamp++;
+  gtk_tree_model_deleted (GTK_TREE_MODEL (tree_store), path);
 
-  if (parent != G_NODE (model->root))
+  if (parent != G_NODE (tree_store->root))
     {
       /* child_toggled */
       if (parent->children == NULL)
        {
          gtk_tree_path_up (path);
 
-         new_iter.stamp = model->stamp;
+         new_iter.stamp = tree_store->stamp;
          new_iter.user_data = parent;
-         gtk_tree_model_has_child_toggled (GTK_TREE_MODEL (model), path, &new_iter);
-       }
-
-      /* revalidate iter */
-      while (parent != G_NODE (model->root))
-       {
-         if (parent->next != NULL)
-           {
-             iter->stamp = model->stamp;
-             iter->user_data = parent->next;
-             break;
-           }
-         parent = parent->parent;
+         gtk_tree_model_has_child_toggled (GTK_TREE_MODEL (tree_store), path, &new_iter);
        }
     }
   gtk_tree_path_free (path);
+
+  /* revalidate iter */
+  if (next_node != NULL)
+    {
+      iter->stamp = tree_store->stamp;
+      iter->user_data = next_node;
+    }
+  else
+    {
+      iter->stamp = 0;
+    }
 }
 
+/**
+ * gtk_tree_store_insert:
+ * @list_store: A #GtkListStore
+ * @iter: An unset #GtkTreeIter to set to the new row
+ * @parent: A valid #GtkTreeIter, or %NULL
+ * @position: position to insert the new row
+ *
+ * Creates a new row at @position.  If parent is non-NULL, then the row will be
+ * made a child of @parent.  Otherwise, the row will be created at the toplevel.
+ * If @position is larger than the number of rows at that level, then the new
+ * row will be inserted to the end of the list.  @iter will be changed to point
+ * to this new row.  The row will be empty before this function is called.  To
+ * fill in values, you need to call @gtk_list_store_set or
+ * @gtk_list_store_set_value.
+ *
+ **/
 void
-gtk_tree_store_insert (GtkTreeStore *model,
+gtk_tree_store_insert (GtkTreeStore *tree_store,
                       GtkTreeIter  *iter,
                       GtkTreeIter  *parent,
                       gint          position)
@@ -931,29 +968,47 @@ gtk_tree_store_insert (GtkTreeStore *model,
   GtkTreePath *path;
   GNode *parent_node;
 
-  g_return_if_fail (GTK_IS_TREE_STORE (model));
+  g_return_if_fail (GTK_IS_TREE_STORE (tree_store));
   if (parent)
-    g_return_if_fail (VALID_ITER (parent, model));
+    g_return_if_fail (VALID_ITER (parent, tree_store));
 
   if (parent)
     parent_node = parent->user_data;
   else
-    parent_node = model->root;
+    parent_node = tree_store->root;
 
-  iter->stamp = model->stamp;
+  iter->stamp = tree_store->stamp;
   iter->user_data = g_node_new (NULL);
   g_node_insert (parent_node, position, G_NODE (iter->user_data));
 
-  path = gtk_tree_store_get_path (GTK_TREE_MODEL (model), iter);
-  gtk_tree_model_inserted (GTK_TREE_MODEL (model), path, iter);
+  path = gtk_tree_store_get_path (GTK_TREE_MODEL (tree_store), iter);
+  gtk_tree_model_inserted (GTK_TREE_MODEL (tree_store), path, iter);
 
   gtk_tree_path_free (path);
 
-  validate_tree ((GtkTreeStore*)model);
+  validate_tree ((GtkTreeStore*)tree_store);
 }
 
+/**
+ * gtk_tree_store_insert_before:
+ * @tree_store: A #GtkTreeStore
+ * @iter: An unset #GtkTreeIter to set to the new row
+ * parent: A valid #GtkTreeIter, or %NULL
+ * @sibling: A valid #GtkTreeIter, or %NULL
+ *
+ * Inserts a new row before @sibling.  If @sibling is %NULL, then the row will
+ * be appended to the beginning of the @parent 's children.  If @parent and
+ * @sibling are %NULL, then the row will be appended to the toplevel.  If both
+ * @sibling and @parent are set, then @parent must be the parent of @sibling.
+ * When @sibling is set, @parent is optional.
+ *
+ * @iter will be changed to point to this new row.  The row will be empty after
+ * this function is called.  To fill in values, you need to call
+ * @gtk_tree_store_set or @gtk_tree_store_set_value.
+ *
+ **/
 void
-gtk_tree_store_insert_before (GtkTreeStore *model,
+gtk_tree_store_insert_before (GtkTreeStore *tree_store,
                              GtkTreeIter  *iter,
                              GtkTreeIter  *parent,
                              GtkTreeIter  *sibling)
@@ -962,17 +1017,17 @@ gtk_tree_store_insert_before (GtkTreeStore *model,
   GNode *parent_node = NULL;
   GNode *new_node;
 
-  g_return_if_fail (GTK_IS_TREE_STORE (model));
+  g_return_if_fail (GTK_IS_TREE_STORE (tree_store));
   g_return_if_fail (iter != NULL);
   if (parent != NULL)
-    g_return_if_fail (VALID_ITER (parent, model));
+    g_return_if_fail (VALID_ITER (parent, tree_store));
   if (sibling != NULL)
-    g_return_if_fail (VALID_ITER (sibling, model));
+    g_return_if_fail (VALID_ITER (sibling, tree_store));
 
   new_node = g_node_new (NULL);
 
   if (parent == NULL && sibling == NULL)
-    parent_node = model->root;
+    parent_node = tree_store->root;
   else if (parent == NULL)
     parent_node = G_NODE (sibling->user_data)->parent;
   else if (sibling == NULL)
@@ -987,19 +1042,37 @@ gtk_tree_store_insert_before (GtkTreeStore *model,
                        sibling ? G_NODE (sibling->user_data) : NULL,
                         new_node);
 
-  iter->stamp = model->stamp;
+  iter->stamp = tree_store->stamp;
   iter->user_data = new_node;
 
-  path = gtk_tree_store_get_path (GTK_TREE_MODEL (model), iter);
-  gtk_tree_model_inserted (GTK_TREE_MODEL (model), path, iter);
+  path = gtk_tree_store_get_path (GTK_TREE_MODEL (tree_store), iter);
+  gtk_tree_model_inserted (GTK_TREE_MODEL (tree_store), path, iter);
 
   gtk_tree_path_free (path);
 
-  validate_tree ((GtkTreeStore*)model);
+  validate_tree ((GtkTreeStore*)tree_store);
 }
 
+/**
+ * gtk_tree_store_insert_after:
+ * @tree_store: A #GtkTreeStore
+ * @iter: An unset #GtkTreeIter to set to the new row
+ * parent: A valid #GtkTreeIter, or %NULL
+ * @sibling: A valid #GtkTreeIter, or %NULL
+ *
+ * Inserts a new row after @sibling.  If @sibling is %NULL, then the row will be
+ * prepended to the beginning of the @parent 's children.  If @parent and
+ * @sibling are %NULL, then the row will be prepended to the toplevel.  If both
+ * @sibling and @parent are set, then @parent must be the parent of @sibling.
+ * When @sibling is set, @parent is optional.
+ *
+ * @iter will be changed to point to this new row.  The row will be empty after
+ * this function is called.  To fill in values, you need to call
+ * @gtk_tree_store_set or @gtk_tree_store_set_value.
+ *
+ **/
 void
-gtk_tree_store_insert_after (GtkTreeStore *model,
+gtk_tree_store_insert_after (GtkTreeStore *tree_store,
                             GtkTreeIter  *iter,
                             GtkTreeIter  *parent,
                             GtkTreeIter  *sibling)
@@ -1008,17 +1081,17 @@ gtk_tree_store_insert_after (GtkTreeStore *model,
   GNode *parent_node;
   GNode *new_node;
 
-  g_return_if_fail (GTK_IS_TREE_STORE (model));
+  g_return_if_fail (GTK_IS_TREE_STORE (tree_store));
   g_return_if_fail (iter != NULL);
   if (parent != NULL)
-    g_return_if_fail (VALID_ITER (parent, model));
+    g_return_if_fail (VALID_ITER (parent, tree_store));
   if (sibling != NULL)
-    g_return_if_fail (VALID_ITER (sibling, model));
+    g_return_if_fail (VALID_ITER (sibling, tree_store));
 
   new_node = g_node_new (NULL);
 
   if (parent == NULL && sibling == NULL)
-    parent_node = model->root;
+    parent_node = tree_store->root;
   else if (parent == NULL)
     parent_node = G_NODE (sibling->user_data)->parent;
   else if (sibling == NULL)
@@ -1035,31 +1108,43 @@ gtk_tree_store_insert_after (GtkTreeStore *model,
                       sibling ? G_NODE (sibling->user_data) : NULL,
                        new_node);
 
-  iter->stamp = model->stamp;
+  iter->stamp = tree_store->stamp;
   iter->user_data = new_node;
 
-  path = gtk_tree_store_get_path (GTK_TREE_MODEL (model), iter);
-  gtk_tree_model_inserted (GTK_TREE_MODEL (model), path, iter);
+  path = gtk_tree_store_get_path (GTK_TREE_MODEL (tree_store), iter);
+  gtk_tree_model_inserted (GTK_TREE_MODEL (tree_store), path, iter);
 
   gtk_tree_path_free (path);
 
-  validate_tree ((GtkTreeStore*)model);
+  validate_tree ((GtkTreeStore*)tree_store);
 }
 
+/**
+ * gtk_tree_store_prepend:
+ * @tree_store: A #GtkTreeStore
+ * @iter: An unset #GtkTreeIter to set to the prepended row
+ * @parent: A valid #GtkTreeIter, or %NULL
+ * 
+ * Prepends a new row to @tree_store.  If @parent is non-NULL, then it will prepend
+ * the new row before the last child of @parent, otherwise it will prepend a row
+ * to the top level.  @iter will be changed to point to this new row.  The row
+ * will be empty after this function is called.  To fill in values, you need to
+ * call @gtk_tree_store_set or @gtk_tree_store_set_value.
+ **/
 void
-gtk_tree_store_prepend (GtkTreeStore *model,
+gtk_tree_store_prepend (GtkTreeStore *tree_store,
                        GtkTreeIter  *iter,
                        GtkTreeIter  *parent)
 {
   GNode *parent_node;
 
-  g_return_if_fail (GTK_IS_TREE_STORE (model));
+  g_return_if_fail (GTK_IS_TREE_STORE (tree_store));
   g_return_if_fail (iter != NULL);
   if (parent != NULL)
-    g_return_if_fail (VALID_ITER (parent, model));
+    g_return_if_fail (VALID_ITER (parent, tree_store));
 
   if (parent == NULL)
-    parent_node = model->root;
+    parent_node = tree_store->root;
   else
     parent_node = parent->user_data;
 
@@ -1067,47 +1152,59 @@ gtk_tree_store_prepend (GtkTreeStore *model,
     {
       GtkTreePath *path;
 
-      iter->stamp = model->stamp;
+      iter->stamp = tree_store->stamp;
       iter->user_data = g_node_new (NULL);
 
       g_node_prepend (parent_node, iter->user_data);
 
-      if (parent_node != model->root)
+      if (parent_node != tree_store->root)
        {
-         path = gtk_tree_store_get_path (GTK_TREE_MODEL (model), parent);
-         gtk_tree_model_has_child_toggled (GTK_TREE_MODEL (model), path, parent);
+         path = gtk_tree_store_get_path (GTK_TREE_MODEL (tree_store), parent);
+         gtk_tree_model_has_child_toggled (GTK_TREE_MODEL (tree_store), path, parent);
          gtk_tree_path_append_index (path, 0);
        }
       else
        {
-         path = gtk_tree_store_get_path (GTK_TREE_MODEL (model), iter);
+         path = gtk_tree_store_get_path (GTK_TREE_MODEL (tree_store), iter);
        }
-      gtk_tree_model_inserted (GTK_TREE_MODEL (model), path, iter);
+      gtk_tree_model_inserted (GTK_TREE_MODEL (tree_store), path, iter);
       gtk_tree_path_free (path);
     }
   else
     {
-      gtk_tree_store_insert_after (model, iter, parent, NULL);
+      gtk_tree_store_insert_after (tree_store, iter, parent, NULL);
     }
 
-  validate_tree ((GtkTreeStore*)model);
+  validate_tree ((GtkTreeStore*)tree_store);
 }
 
+/**
+ * gtk_tree_store_append:
+ * @tree_store: A #GtkTreeStore
+ * @iter: An unset #GtkTreeIter to set to the appended row
+ * @parent: A valid #GtkTreeIter, or %NULL
+ * 
+ * Appends a new row to @tree_store.  If @parent is non-NULL, then it will append the
+ * new row after the last child of @parent, otherwise it will append a row to
+ * the top level.  @iter will be changed to point to this new row.  The row will
+ * be empty after this function is called.  To fill in values, you need to call
+ * @gtk_tree_store_set or @gtk_tree_store_set_value.
+ **/
 void
-gtk_tree_store_append (GtkTreeStore *model,
+gtk_tree_store_append (GtkTreeStore *tree_store,
                       GtkTreeIter  *iter,
                       GtkTreeIter  *parent)
 {
   GNode *parent_node;
 
-  g_return_if_fail (GTK_IS_TREE_STORE (model));
+  g_return_if_fail (GTK_IS_TREE_STORE (tree_store));
   g_return_if_fail (iter != NULL);
 
   if (parent != NULL)
-    g_return_if_fail (VALID_ITER (parent, model));
+    g_return_if_fail (VALID_ITER (parent, tree_store));
 
   if (parent == NULL)
-    parent_node = model->root;
+    parent_node = tree_store->root;
   else
     parent_node = parent->user_data;
 
@@ -1115,58 +1212,85 @@ gtk_tree_store_append (GtkTreeStore *model,
     {
       GtkTreePath *path;
 
-      iter->stamp = model->stamp;
+      iter->stamp = tree_store->stamp;
       iter->user_data = g_node_new (NULL);
 
       g_node_append (parent_node, G_NODE (iter->user_data));
 
-      if (parent_node != model->root)
+      if (parent_node != tree_store->root)
        {
-         path = gtk_tree_store_get_path (GTK_TREE_MODEL (model), parent);
-         gtk_tree_model_has_child_toggled (GTK_TREE_MODEL (model), path, parent);
+         path = gtk_tree_store_get_path (GTK_TREE_MODEL (tree_store), parent);
+         gtk_tree_model_has_child_toggled (GTK_TREE_MODEL (tree_store), path, parent);
          gtk_tree_path_append_index (path, 0);
        }
       else
        {
-         path = gtk_tree_store_get_path (GTK_TREE_MODEL (model), iter);
+         path = gtk_tree_store_get_path (GTK_TREE_MODEL (tree_store), iter);
        }
 
-      gtk_tree_model_inserted (GTK_TREE_MODEL (model), path, iter);
+      gtk_tree_model_inserted (GTK_TREE_MODEL (tree_store), path, iter);
       gtk_tree_path_free (path);
     }
   else
     {
-      gtk_tree_store_insert_before (model, iter, parent, NULL);
+      gtk_tree_store_insert_before (tree_store, iter, parent, NULL);
     }
 
-  validate_tree ((GtkTreeStore*)model);
+  validate_tree ((GtkTreeStore*)tree_store);
 }
 
+/**
+ * gtk_tree_store_is_ancestor:
+ * @tree_store: A #GtkTreeStore
+ * @iter: A valid #GtkTreeIter
+ * @descendant: A valid #GtkTreeIter
+ * 
+ * Returns %TRUE if @iter is an ancestor of @descendant.  That is, @iter is the
+ * parent (or grandparent or great-grandparent) of @descendant.
+ * 
+ * Return value: %TRUE, if @iter is an ancestor of @descendant
+ **/
 gboolean
-gtk_tree_store_is_ancestor (GtkTreeStore *model,
+gtk_tree_store_is_ancestor (GtkTreeStore *tree_store,
                            GtkTreeIter  *iter,
                            GtkTreeIter  *descendant)
 {
-  g_return_val_if_fail (GTK_IS_TREE_STORE (model), FALSE);
-  g_return_val_if_fail (VALID_ITER (iter, model), FALSE);
-  g_return_val_if_fail (VALID_ITER (descendant, model), FALSE);
+  g_return_val_if_fail (GTK_IS_TREE_STORE (tree_store), FALSE);
+  g_return_val_if_fail (VALID_ITER (iter, tree_store), FALSE);
+  g_return_val_if_fail (VALID_ITER (descendant, tree_store), FALSE);
 
   return g_node_is_ancestor (G_NODE (iter->user_data),
                             G_NODE (descendant->user_data));
 }
 
 
+/**
+ * gtk_tree_store_iter_depth:
+ * @tree_store: A #GtkTreeStore
+ * @iter: A valid #GtkTreeIter
+ * 
+ * Returns the depth of @iter.  This will be 0 for anything on the root level, 1
+ * for anything down a level, etc.
+ * 
+ * Return value: The depth of @iter
+ **/
 gint
-gtk_tree_store_iter_depth (GtkTreeStore *model,
+gtk_tree_store_iter_depth (GtkTreeStore *tree_store,
                           GtkTreeIter  *iter)
 {
-  g_return_val_if_fail (GTK_IS_TREE_STORE (model), 0);
-  g_return_val_if_fail (VALID_ITER (iter, model), 0);
+  g_return_val_if_fail (GTK_IS_TREE_STORE (tree_store), 0);
+  g_return_val_if_fail (VALID_ITER (iter, tree_store), 0);
 
   return g_node_depth (G_NODE (iter->user_data)) - 1;
 }
 
 
+/**
+ * gtk_tree_store_clear:
+ * @tree_store: @ #GtkTreeStore
+ * 
+ * Removes all rows from @tree_store
+ **/
 void
 gtk_tree_store_clear (GtkTreeStore *tree_store)
 {